/**
 * Knowledge Base and RAG Types
 * 
 * 知识库与 RAG 系统的核心类型定义
 */

/**
 * 文档类型
 */
export type DocumentType = 
  | 'pdf'
  | 'markdown'
  | 'text'
  | 'code'
  | 'word'
  | 'excel'
  | 'other';

/**
 * 文档元数据
 */
export interface DocumentMetadata {
  /** 文件名 */
  filename: string;
  /** 文件类型 */
  fileType: DocumentType;
  /** 文件大小（字节） */
  fileSize: number;
  /** MIME 类型 */
  mimeType?: string;
  /** 页数（仅 PDF） */
  pageCount?: number;
  /** 字符数 */
  characterCount?: number;
  /** 语言 */
  language?: string;
  /** 创建时间 */
  createdAt?: Date;
  /** 最后修改时间 */
  modifiedAt?: Date;
  /** 自定义标签 */
  tags?: string[];
  /** 作者 */
  author?: string;
  /** 额外元数据 */
  [key: string]: any;
}

/**
 * 文档
 */
export interface Document {
  /** 文档唯一标识 */
  id: string;
  /** 知识库 ID */
  knowledgeBaseId: string;
  /** 文档内容（纯文本） */
  content: string;
  /** 元数据 */
  metadata: DocumentMetadata;
  /** 创建时间 */
  createdAt: Date;
  /** 更新时间 */
  updatedAt: Date;
}

/**
 * 文档块（Chunk）
 */
export interface DocumentChunk {
  /** 块唯一标识 */
  id: string;
  /** 文档 ID */
  documentId: string;
  /** 知识库 ID */
  knowledgeBaseId: string;
  /** 块索引 */
  index: number;
  /** 块内容 */
  content: string;
  /** 嵌入向量 */
  embedding?: number[];
  /** 块元数据 */
  metadata: {
    /** 起始字符位置 */
    startChar: number;
    /** 结束字符位置 */
    endChar: number;
    /** 字符数 */
    charCount: number;
    /** 页码（如适用） */
    pageNumber?: number;
    /** 章节标题（如适用） */
    sectionTitle?: string;
    /** 额外元数据 */
    [key: string]: any;
  };
  /** 创建时间 */
  createdAt: Date;
}

/**
 * 知识库
 */
export interface KnowledgeBase {
  /** 知识库唯一标识 */
  id: string;
  /** 知识库名称 */
  name: string;
  /** 描述 */
  description?: string;
  /** 文档数量 */
  documentCount: number;
  /** 总字符数 */
  totalCharacters: number;
  /** 块数量 */
  chunkCount: number;
  /** 创建时间 */
  createdAt: Date;
  /** 更新时间 */
  updatedAt: Date;
  /** 标签 */
  tags?: string[];
  /** 配置 */
  config: KnowledgeBaseConfig;
}

/**
 * 知识库配置
 */
export interface KnowledgeBaseConfig {
  /** 块大小（字符数） */
  chunkSize: number;
  /** 块重叠（字符数） */
  chunkOverlap: number;
  /** 嵌入模型 */
  embeddingModel: string;
  /** 检索配置 */
  retrieval: {
    /** 返回的最大块数 */
    topK: number;
    /** 相似度阈值 */
    similarityThreshold: number;
    /** 是否启用重排序 */
    enableReranking: boolean;
  };
}

/**
 * 文档处理器接口
 */
export interface DocumentProcessor {
  /** 支持的文件类型 */
  supportedTypes: DocumentType[];
  /** 解析文档 */
  parse(file: File): Promise<{
    content: string;
    metadata: Partial<DocumentMetadata>;
  }>;
  /** 验证文件 */
  validate(file: File): Promise<{ valid: boolean; error?: string }>;
}

/**
 * 文档分块器
 */
export interface DocumentChunker {
  /** 分块策略 */
  strategy: 'fixed' | 'sentence' | 'paragraph' | 'semantic';
  /** 分块 */
  chunk(
    content: string,
    config: Pick<KnowledgeBaseConfig, 'chunkSize' | 'chunkOverlap'>
  ): DocumentChunk[];
}

/**
 * 向量存储接口
 */
export interface VectorStore {
  /** 初始化 */
  initialize(): Promise<void>;
  /** 索引文档块 */
  indexChunks(chunks: DocumentChunk[]): Promise<void>;
  /** 搜索相似块 */
  search(query: string, topK: number): Promise<SearchResult[]>;
  /** 删除文档 */
  deleteDocument(documentId: string): Promise<void>;
  /** 删除知识库 */
  deleteKnowledgeBase(knowledgeBaseId: string): Promise<void>;
  /** 获取统计信息 */
  getStats(): Promise<VectorStoreStats>;
}

/**
 * 搜索结果
 */
export interface SearchResult {
  /** 文档块 */
  chunk: DocumentChunk;
  /** 相似度分数 (0-1) */
  score: number;
  /** 文档元数据 */
  documentMetadata: DocumentMetadata;
}

/**
 * 向量存储统计
 */
export interface VectorStoreStats {
  /** 总文档数 */
  totalDocuments: number;
  /** 总块数 */
  totalChunks: number;
  /** 总向量数 */
  totalVectors: number;
  /** 存储大小（字节） */
  storageSize: number;
}

/**
 * RAG 配置
 */
export interface RAGConfig {
  /** 是否启用 RAG */
  enabled: boolean;
  /** 知识库 ID 列表 */
  knowledgeBaseIds: string[];
  /** 检索的最大块数 */
  topK: number;
  /** 相似度阈值 */
  similarityThreshold: number;
  /** 上下文窗口大小（字符数） */
  contextWindowSize: number;
  /** 是否显示来源引用 */
  showSources: boolean;
  /** 提示词模板 */
  promptTemplate?: string;
}

/**
 * RAG 增强的查询请求
 */
export interface RAGEnhancedQuery {
  /** 原始用户查询 */
  query: string;
  /** 检索到的上下文 */
  context: SearchResult[];
  /** 增强后的提示词 */
  enhancedPrompt: string;
  /** 使用的知识库 */
  knowledgeBases: string[];
}

/**
 * RAG 响应
 */
export interface RAGResponse {
  /** 响应内容 */
  content: string;
  /** 使用的来源 */
  sources: SearchResult[];
  /** 相关度分数 */
  relevanceScore?: number;
}

/**
 * 嵌入生成器接口
 */
export interface EmbeddingGenerator {
  /** 模型名称 */
  modelName: string;
  /** 向量维度 */
  dimensions: number;
  /** 生成嵌入 */
  generate(text: string): Promise<number[]>;
  /** 批量生成嵌入 */
  generateBatch(texts: string[]): Promise<number[][]>;
}

/**
 * 文档上传进度
 */
export interface DocumentUploadProgress {
  /** 文档 ID */
  documentId: string;
  /** 文件名 */
  filename: string;
  /** 进度状态 */
  status: 'parsing' | 'chunking' | 'embedding' | 'indexing' | 'completed' | 'failed';
  /** 进度百分比 (0-100) */
  progress: number;
  /** 当前步骤描述 */
  currentStep?: string;
  /** 错误信息 */
  error?: string;
}

/**
 * 知识库统计
 */
export interface KnowledgeBaseStatistics {
  /** 知识库 ID */
  knowledgeBaseId: string;
  /** 文档数量 */
  documentCount: number;
  /** 块数量 */
  chunkCount: number;
  /** 总字符数 */
  totalCharacters: number;
  /** 平均块大小 */
  averageChunkSize: number;
  /** 文档类型分布 */
  documentTypeDistribution: Record<DocumentType, number>;
  /** 最近更新时间 */
  lastUpdated: Date;
  /** 查询次数 */
  queryCount: number;
  /** 最近查询时间 */
  lastQueried?: Date;
}

